Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

WebViewController

The WebViewController class allows you to display and interact with embedded web content inside your script. It is designed for use cases like custom in-app browsers, rendering dynamic HTML, or communicating with JavaScript running in a web context.

Class: WebViewController

1const webView = new WebViewController()

Properties

shouldAllowRequest?: (request) => Promise<boolean>

An optional callback that determines whether to allow or block a request made by the WebView. This function is invoked before each resource is loaded, such as when navigating to a new page or submitting a form.

This is useful for intercepting navigation actions, implementing custom security logic, or filtering unwanted requests (e.g., ad domains).

Parameters

The function receives a single request object with the following properties:

  • url: string The full URL of the request.

  • method: string The HTTP method (e.g., GET, POST).

  • body?: Data | null Optional body data sent with the request (e.g., for POST requests).

  • headers: Record<string, string> HTTP request headers.

  • timeoutInterval: number The timeout interval in seconds for the request.

  • navigationType: "linkActivated" | "reload" | "backForward" | "formResubmitted" | "formSubmitted" | "other" The context that triggered the navigation.

Returns

A Promise<boolean> resolving to:

  • true: allow the request to proceed
  • false: block the request

Example

1const webView = new WebViewController()
2
3webView.shouldAllowRequest = async (request) => {
4  console.log('Intercepted request to:', request.url)
5
6  // Block all requests to example.com
7  if (request.url.includes('example.com')) {
8    return false
9  }
10
11  return true
12}
13
14await webView.loadURL('https://www.wikipedia.org')
15await webView.present({ navigationTitle: 'Filtered WebView' })

Methods

loadURL(url: string): Promise<boolean>

Loads a webpage by its URL.

  • Parameters:

    • url: The full URL of the webpage to load.

  • Returns: Promise<boolean> — Resolves to true if the load succeeds.

loadHTML(html: string, baseURL?: string): Promise<boolean>

Loads a web page using raw HTML content.

  • Parameters:

    • html: The HTML string to render.
    • baseURL (optional): A base URL to resolve relative paths.

  • Returns: Promise<boolean> — Resolves to true on successful load.

loadData(data: Data, mimeType: string, encoding: string, baseURL: string): Promise<boolean>

Loads web content from raw data.

  • Parameters:

    • data: The binary content to load.
    • mimeType: MIME type of the content (e.g., "text/html").
    • encoding: Character encoding (e.g., "utf-8").
    • baseURL: Base URL for resolving relative URLs.

  • Returns: Promise<boolean>

waitForLoad(): Promise<boolean>

Waits until the WebView has finished loading content.

  • Returns: Promise<boolean>

getHTML(): Promise<string | null>

Returns the current HTML content of the page.

  • Returns: Promise<string | null>

evaluateJavaScript<T = any>(javascript: string): Promise<T>

Evaluates the specified JavaScript string in the context of the WebView.

  • Parameters:

    • javascript: A JavaScript code string to be evaluated. To retrieve a result from JavaScript, the code must explicitly use the return keyword.

  • Returns: Promise<T> — Resolves with the result of the JavaScript evaluation. If the JavaScript code returns a value, it will be returned as the resolved value of the Promise.

Example

1const webView = new WebViewController()
2await webView.loadURL("https://example.com")
3const title = await webView.evaluateJavaScript("return document.title") // Must use `return`
4console.log(title) // "Example Domain"
5webView.dispose()

Another example:

1const webView = new WebViewController()
2await webView.loadHTML(`
3  <html>
4    <body>
5      <script>
6        window.myValue = 42
7      </script>
8    </body>
9  </html>
10`)
11
12await webView.waitForLoad()
13
14const result = await webView.evaluateJavaScript('return window.myValue')
15console.log(result) // 42

addScriptMessageHandler<P = any, R = any>(name: string, handler: (params?: P) => R): Promise<void>

Installs a message handler callable from JavaScript in the web page, and enables sending a reply back from native code.

  • Parameters:

    • name: The message handler name. Must be unique and non-empty.
    • handler: A callback function that receives parameters from JavaScript and returns a value. The return value will be sent back as the JavaScript promise resolution.

  • Returns: Promise<void> — Resolves when the message handler is added successfully.

Example

1let webView = new WebViewController()
2
3await webView.addScriptMessageHandler("sayHi", (greeting: string) => {
4  console.log("Receive a message", greeting)
5  return "Hello!"
6})
7
8await webView.loadHTML(`
9  <html>
10    <body>
11      <script>
12        (async () => {
13          const response = await window.webkit.messageHandlers.sayHi.postMessage("Hi!")
14          alert(response) // Shows: "Hello!"
15        })()
16      </script>
17    </body>
18  </html>
19`)

present(options?: { fullscreen?: boolean, navigationTitle?: string }): Promise<void>

Presents the WebView in a modal sheet.

  • Options:

    • fullscreen: If true, displays the WebView in fullscreen mode.
    • navigationTitle: Optional title for the navigation bar.

  • Returns: Promise<void>

canGoBack(): Promise<boolean>

Checks whether the WebView can go back in history.

canGoForward(): Promise<boolean>

Checks whether the WebView can go forward in history.

goBack(): Promise<boolean>

Navigates to the previous page in the history stack.

goForward(): Promise<boolean>

Navigates to the next page in the history stack.

reload(): Promise<void>

Reloads the current webpage.

dismiss(): void

Dismisses the WebView if currently presented.

dispose(): void

Disposes the WebView instance and releases resources.

  • If the WebView is still presented, it will first be dismissed.
  • Important: You must call this to prevent memory leaks when done.

Full Example

1const webView = new WebViewController()
2
3await webView.addScriptMessageHandler('greet', (name) => {
4  return `Hello, ${name}`
5})
6
7await webView.loadHTML(`
8  <html>
9    <body>
10      <h1>Custom WebView</h1>
11      <button onclick="sendMessage()">Greet</button>
12      <script>
13        async function sendMessage() {
14          const response = await window.webkit.messageHandlers.greet.postMessage("Alice")
15          alert(response)
16        }
17      </script>
18    </body>
19  </html>
20`)
21
22await webView.present({ navigationTitle: 'WebView Demo' })
23webView.dispose()
Outline